Overview of IDL Keyword Processing

IDL keyword processing can seem confusing at first glance, due to the interrelated data structures involved. However, as the examples that follow in this section will show, the concepts involved are relatively straightforward once you have seen and understood a concrete example such as Keyword Examples.

Following is a skeleton of a system routine that accepts keyword arguments. These elements must be present in any such system routine:

void keyword_sysrtn_skeleton(int argc, IDL_VPTR *argv, char *argk)

{

typedef struct {

IDL_KW_RESULT_FIRST_FIELD; /* Must be first entry in struct */

... /* Variables specific to your keywords go here */

} KW_RESULT;

static IDL_KW_PAR kw_pars[] = {

 

/*

* Keyword definitions for the keywords you accept go here,

* one definition per keyword. The keyword definitions refer

* to fields within the KW_RESULT type defined above.

*/

...

 

{ NULL } /* List must be NULL terminated */

 

};

KW_RESULT kw; /* Variable which will hold the keyword values */

 

(void) IDL_KWProcessByOffset(argc, argv, argk, kw_pars,

   (IDL_VPTR *) 0, 1, &kw);

/* The body of your routine */

 

IDL_KW_FREE;

}

IDL keyword processing is made up of the following data structures and steps:

• A NULL terminated array of IDL_KW_PAR structures must be present. Each entry in this array describes the keyword processing required for a single keyword.
• If a keyword represents an input-only, by-value array, the IDL_KW_PAR structure that describes it points at an auxiliary IDL_KW_ARR_DESC_R structure that supplies the additional array specific information.
• The system routine must declare a local type definition named KW_RESULT, and a variable of this type named kw. The KW_RESULT type contains all of the data fields that will be set as a result of processing the keywords described by the IDL_KW_PAR and IDL_KW_ARR_DESC_R structures described above. The IDL_KW_PAR and IDL_KW_ARR_DESC_R structures refer to the fields of the KW_RESULT structure by their offset from the beginning of the structure. The IDL_KW_OFFSETOF() macro is used to compute this offset.
• The system routine calls the IDL_KWProcessByOffset() function, passing it the address of the IDL_KW_PAR array, and the KW_RESULT variable (kw).
• After IDL_KWProcessByOffset() is called, the KW_RESULT structure (kw) contains the results, which can be accessed freely by the system routine.
• Before returning, the system routine must invoke the IDL_KW_FREE macro. This macro ensures that any dynamic memory used by IDL_KWProcessByOffset() is properly released.
• System routines are not required to, and generally do not, call IDL_KW_FREE before throwing errors using IDL_Message() with the IDL_MSG_LONGJMP or IDL_MSG_IO_LONGJMP action codes. In these cases, the IDL interpreter automatically knows to release the resources used by keyword processing on your behalf.